/**
 **********************************************************************************************************************
 * @file       cot_led.h
 * @brief      轻量级LED控制模块头文件
 *
 * 该头文件定义了LED控制模块的接口函数和数据类型
 **********************************************************************************************************************
 */

/* Define to prevent recursive inclusion -----------------------------------------------------------------------------*/
#ifndef _COT_LED_H_
#define _COT_LED_H_

/* Includes ----------------------------------------------------------------------------------------------------------*/
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

/* Exported types ----------------------------------------------------------------------------------------------------*/

/* 状态bit位所使用的byte数，bit之间的控制时间为时间颗粒度 */
/* 状态位数组的字节数,决定了最大能存储多少个状态 */
/* 例如:4字节可以存储32个状态,每个状态对应一个最小时间间隔 */
#define LED_STATE_BYTE_NUM 4

/* LED亮灭状态枚举 */
typedef enum
{
    COT_LED_OFF = 0,          /* (0)LED熄灭 */
    COT_LED_ON = !COT_LED_OFF /* (1)LED点亮 */
} cotLedState_e;

/* LED控制回调函数类型 */
typedef void (*cotLedCtrl_f)(cotLedState_e state);

/* LED句柄类型 */
typedef uint16_t led_t;

/* LED控制过程结构体 */
typedef struct
{
    uint8_t validBits;      /* 状态位数组中有效的位数 */
    uint8_t offset;         /* 当前正在处理的状态位偏移 */
    uint8_t count;          /* 剩余的控制次数 */
    uint8_t isSetCount : 1; /* 是否设置了控制次数 */
    uint8_t defState : 1;   /* 次数用完后的默认状态 */
    uint8_t curState : 1;   /* LED当前的实际状态 */
    uint8_t pwmDir : 1;     /* PWM占空比变化方向:1递增,0递减 */
    uint8_t isPwm : 1;      /* 是否使用PWM模式(用于呼吸灯) */
    uint16_t tic;           /* 状态更新计时器 */
    uint16_t interval;      /* 状态更新时间间隔,单位毫秒 */
    union
    {
        struct
        {
            uint16_t onTime;               /* PWM高电平时间 */
            uint16_t tic;                  /* PWM周期计时器 */
        } pwm;                             /* PWM相关参数(用于呼吸灯) */
        uint8_t state[LED_STATE_BYTE_NUM]; /* 状态位数组,每位表示一个时间间隔内LED的状态 */
    } data;                                /* LED控制数据 */
} cotLedProc_t;

/* LED配置结构体 */
typedef struct
{
    cotLedProc_t proc;       /* LED控制过程 */
    cotLedCtrl_f pfnLedCtrl; /* LED控制回调函数 */
} cotLedCfg_t;

/* Exported constants ------------------------------------------------------------------------------------------------*/
/* Exported macro ----------------------------------------------------------------------------------------------------*/
/* Exported functions ------------------------------------------------------------------------------------------------*/

/* LED初始化函数 */
extern int cotLed_Init(cotLedCfg_t pCfgTable[], size_t num);

/* LED基本控制函数 */
extern int cotLed_SetState(led_t led, cotLedState_e state);
extern int cotLed_SetStateWithTime(led_t led, cotLedState_e state, uint16_t time);
extern int cotLed_ON(led_t led);
extern int cotLed_OFF(led_t led);
extern int cotLed_Toggle(led_t led);

/* LED闪烁控制函数 */
extern int cotLed_Twinkle(led_t led, uint16_t time);
extern int cotLed_TwinkleWithCount(led_t led, uint16_t time, uint8_t count, cotLedState_e defState);

/* LED呼吸灯函数 */
extern int cotLed_Breathe(led_t led, uint16_t period);
extern int cotLed_BreatheWithCount(led_t led, uint16_t period, uint8_t count, cotLedState_e defState);

/* LED自定义控制函数 */
extern int cotLed_Custom(led_t led, ...);
extern int cotLed_CustomWithCount(led_t led, uint8_t count, cotLedState_e defState, ...);

/* LED组合效果函数 */
extern int cotLed_Marquee(led_t led[], uint8_t ledNum, int32_t time);
extern int cotLed_MarqueeWithCount(led_t led[], uint8_t ledNum, int32_t time, uint8_t count, cotLedState_e defState);
extern int cotLed_Waterfall(led_t led[], uint8_t ledNum, int32_t time);
extern int cotLed_WaterfallWithCount(led_t led[], uint8_t ledNum, int32_t time, uint8_t count, cotLedState_e defState);

/* LED控制周期任务函数 */
extern int cotLed_Ctrl(uint32_t sysTime);

#endif
